Skip to content

Check whether a dose series supports tests in each cell type - #80

Merged
parashardhapola merged 8 commits into
masterfrom
dose/05-dose-design-check
Nov 20, 2026
Merged

parashardhapola merged 8 commits into
masterfrom
dose/05-dose-design-check

Conversation

@parashardhapola

Copy link
Copy Markdown
Member

The problem

A dose analysis compares each dose with the vehicle, the samples given no dose, and judges every difference against the variation between replicates given the same dose. In a single-cell dose series that comparison can fail in one cell type and not another, and nothing in CytePool says so before a fit:

  • Replicates. In a survey of 130 single-cell studies with three or more dose groups, 57 had no biological replicate per dose, and four clinical studies had no placebo arm in their single-cell data. Without replicates at the treated doses, curves can describe the means but not support p-values or bounds.
  • Filtering. Pseudobulk fits leave out the profiles of too few cells. A cell type that thins with dose can lose a dose group, or its vehicle, while others keep every sample; dreamlet's documentation warns that filtering can remove a level of an ordered covariate from some cell types (Hoffman et al. 2026). Aggregation-based methods performed decently from about 100 cells per cell type and sample in muscat's benchmark (Crowell et al. 2020), so the cells behind each profile matter too.
  • Batches. A dose processed in a lane or plate of its own cannot be told apart from that batch: plate effects confounded with the condition break the control of false positives, which summing within plates restores (Lun and Marioni 2017).
  • Regulatory minimums. EPA's Transcriptomic Assessment Products ask for a vehicle and at least 8 doses spaced by half a log10, 4 animals of each sex per dose, and at least 2 passing samples per dose level and 3 vehicle samples (US EPA 2024, Sec. 3.4.1.3, 3.4.2 and 3.4.5.2). MCP-Mod's test step needs 3 distinct doses with placebo and its modelling step 4 (EMA 2014).

The solution

cp.check_dose_design reports, for every cell type of a cube, what its dose series supports, before anything is fitted:

axis = cp.DoseAxis("dose", unit="ug/kg", metric="administered")
design = cp.Design(cube.samples, "~ 1")  # the terms other than dose
report = cp.check_dose_design(cube, design, dose=axis, batch="lane", rules="etap_2024", sex="sex")
print(report)
report.status("stellate")                                      # 'inferential'
report.doses.filter(group_id="stellate", n_samples_used=1)     # the dose group that keeps one mouse
report.minimums.filter(met=False)                              # ETAP's minimums the design misses
  • Each cell type uses the samples its fit in limma_voom would use (min_cells, min_counts). doses gives, per cell type and dose group, the samples used and left out and the fewest cells and counts; samples gives each sample's cells, counts and why it was left out, in limma_voom's words.
  • The design holds the terms other than dose; the check adds an intercept and an indicator of each treated dose group that keeps a sample, takes the rank by R's qr() rule, and calls a dose group estimable when its column, placed last, lies outside the span of the others, as limma's nonEstimable reports it.
  • The replicates of a dose group are its samples or, when the design has random intercepts, the levels of each grouping among them: two samples of one animal at a dose, under (1 | animal), are one replicate.
  • With batch, a dose group is confounded when it is estimable and the batches absorb it beside the design's other terms; batches of a single sample are pooled into one, and a sample alone in its batch, when it is the only one, joins none. A lane per sample confounds nothing; the vehicle alone in its lane confounds every dose. The rule finds exact confounding, and the documentation advises adding a known batch to the design whenever it is unbalanced across the doses.
  • Each cell type is inferential (tests with p-values and curves with bounds), descriptive (curves that describe the means: no estimable treated dose group has a second replicate, no residual degrees of freedom, or a batch confounds a dose group and the design does not compare them through a random intercept of the batch over two or more batches of the vehicle and of each such group) or refused (no samples, no vehicle, no treated sample, no estimable group, or random intercepts that cannot be estimated beside the dose groups), with a reason that says what to do.
  • With rules="etap_2024", minimums lists each of ETAP's minimums that samples show, met or not, with what ETAP does when it is unmet (when_unmet): a deviation from the design, a dose level excluded, or a dose response not modelled. rules_status is "deviation" when a minimum of the design or a vehicle minimum is unmet; a level that ETAP excludes leaves it "met", since ETAP's procedure goes on without it, and the printout names the level.

A new chapter, "Dose response", after "Composition tests", takes the sections on dose axes and on simulated dose series (#79) from "Designs, linear models and contrasts" and adds what a number of dose groups supports (from one comparison at 2 groups to ETAP's 9), the check with an example that the tests run, and ETAP's minimums.

Why it matters

PR 7's dose_response runs a cell type only where the check allows, on the samples it marks used, and gives descriptive cell types no p-values; PR 10 counts its spare dose groups from n_dose_groups_estimable; PR 14 applies ETAP's exclusion of levels, which the report already lists; PR 16's records carry the unmet minimums. On GSE208161, one participant per dose level sampled before and after dosing (Sonigra et al. 2022), 13 of 18 clusters keep one residual degree of freedom, the placebo participant's change from baseline, and limma_voom would fit them; the check calls all 18 descriptive. The PR builds on PR 3's DoseAxis (#78) and on PR 1's recorded runs (#77), and shares the reading of dose columns with PR 6's simulator (#79).

Validation

validation/dose_design.py, run on Modal: 46 checks, 44 pass and 2 information, none failed; second of two runs in one container 6.8 s and 520 MiB.

Check Reference Compared Tier Largest difference
Counts scanpy 1.12.4 get.aggregate, pandas 3.1.0 Cells, counts and use of 96 samples, and samples used and left out with the fewest cells and counts of 36 dose groups, at min_counts 0 and 10,678, on 7,277 simulated cells of a TCDD-like series identical 0 mismatches (4 checks)
Aliasing and statuses R 4.4.3 qr(), limma 3.62.1 nonEstimable; statuses by the rules coded again in R Samples used, residual df, estimable dose groups, groups confounded with a batch and statuses of 25 designs (32 cell types), among them lanes shared by two samples or split between low and high doses, one sample alone in its lane, sex and lane that absorb a dose only together, replicated groups without residual df, and four designs with a random intercept of the lane or the animal identical 0 mismatches (25 checks)
ETAP's minimums ETAP 2024 coded again in R from Sec. 3.4.1.3, 3.4.2 and 3.4.5.2 Met and observed text of 128 rows of 13 designs, among them 10 ladders with steps on either side of the 0.05 log10 tolerance and a design in which ETAP excludes a level identical 0 mismatches (13 checks)
Published data GSE208161's per-cell metadata and the published design Cells and RNA counts of 8 samples x 18 clusters; every cluster descriptive under ~ patient identical; pass 0 mismatches; 18 of 18 descriptive
Information GSE208161 Under ~ 1, 18 descriptive; with the day-29 samples alone, 16 descriptive and clusters 14 and 17 refused none

validation/dose_axes.py ran again, since its checked code changed (the reading of dose columns and the axis's column names moved into cytepool/_doses.py), and printed PR 3's table line for line (234 checks; 15.9 s, 350 MiB). Modal runs, all ephemeral in cytearc_profiling: four run --scripts dose_design.py --write-fixtures on 2 CPU and 4 GiB (the first stopped in R on a zero-length name, fixed; the others passed and wrote the fixtures, the last in 21 s after the review's changes), and three containers on 4 CPU and 8 GiB that ran the scripts twice each (77 s and 65 s for both scripts, then 32 s for dose_design.py alone after a last change to its checked code; its numbers above are from that run).

The helper docs/changed_since_run.py also lists 30 scripts. Master lists 29 of them too, whose checked code changed before this PR: activity.py, combined_p_values_and_replication.py, composition_tests.py, cube_collection.py, deseq2_tests.py, design.py, differential_expression.py, differential_expression_options.py, dream.py, empirical_bayes.py, gene_set_files_and_ora.py, gene_set_tests.py, gsea.py, interferon_stimulated_pbmcs.py, kenward_roger_and_f_tests.py, linear_models.py, meta_analysis.py, mixed_models.py, multiple_testing.py, negative_binomial_fits.py, pathway_scores.py, pca_and_dot_plots.py, plotting.py, quasi_likelihood.py, rotation_gene_set_tests.py, sample_quality_weights.py, sumrank.py, variance_partitioning.py and voom.py. The 30th, simulate_dose_series.py, checks the reading of dose columns and DoseAxis, which this PR extends; tests/test_simulate_dose_series.py passes against its fixtures unchanged. This PR changes none of their results. Master also lists dose_axes.py, whose checked code #79 moved into cytepool/_doses.py; this PR's run of it is current.

Tests

tests/test_dose_designs.py (40 tests) checks the report against the fixtures of the validation script (scanpy's sums and pandas' tables, R's aliasing, ETAP's minimums in R, GSE208161), against rules derived by hand (statuses of small designs, replicates counted after filtering and only in groups that can be compared, the units a random intercept names, batch confounding on a dozen lane layouts with a sample alone in its lane among them, a random intercept of the batch over one or two lanes of the vehicle, other terms that absorb dose groups, a unit nested one to one in the dose groups and its pooled cube, ETAP's steps on both sides of the tolerance, a level ETAP excludes), against limma_voom's own choice of samples, and against invariants (sample order, design rows in another order than the cube, dose units, labels). Every refusal is tested with its message, each column of the axis by the name DoseAxis.design_columns gives it, and the chapter's example runs, with the fit it leads to, the printout it shows and the values it states. 51 deliberate bugs were caught, 24 in the build and 27 after the review, among them one pivoted QR in place of the column-last rule, a lone single-sample batch given a column of its own, replicates counted as samples under a random intercept, a random intercept of the batch excusing every confounded group, the design's rows left out of cube order, the vehicle counted in the replication rule, animals counted after filtering, and an excluded level counted as a deviation; each rule's mutation is caught by a test derived by hand, not only by the fixtures. Coverage of cytepool/dose_designs.py, cytepool/_doses.py and cytepool/dose_axes.py is 100% of statements and branches with NUMBA_DISABLE_JIT=1. tests/test_dose_axes.py and tests/test_simulate_dose_series.py pass unchanged but for the chapter they read.

Decisions

Decision Alternatives Reason
Descriptive when no estimable treated dose group keeps two samples, when no residual degrees of freedom are left, or when an unmodelled batch confounds a dose group Descriptive as soon as any dose group keeps one sample; residual degrees of freedom alone Dose effects are judged against replicates given a dose; a top dose that keeps one mouse beside 8 replicated groups stays testable, flagged in doses, while residual df alone would call 13 of GSE208161's clusters inferential on the placebo participant's change from baseline
Dose groups of one sample kept; a group dropped only when it keeps no sample ETAP's rule, drop groups below 2 Dropping by default turns unreplicated designs into refusals instead of descriptive curves; minimums lists the levels ETAP excludes, for PR 14
The design holds the terms other than dose, and a design that uses the dose column or the axis's columns is refused Strip PR 3's dose columns from the design One convention with PR 7's dose_response; stripping by name would miss columns computed from the dose under other names
Estimability by placing each dose column last under R's qr() rule One pivoted QR A single pivoted QR depends on column order: on two lanes splitting low and high doses it reports dose 30 alone, missing dose 10
Batches of one sample pooled, a sample alone in its batch joining none, and the batch checked beside the design's other terms An exemption only when every batch holds one sample; a lone batch with a column of its own; batch columns alone Without pooling, two vehicle samples sharing one of eight lanes would confound every dose; a column for a lone batch absorbed its one sample, so a dose kept by that sample alone counted as confounded; without the other terms, sex and lane that absorb a dose only together go unseen
Confounding with a batch is exact: the dose group's difference from the vehicle lies among the batches' differences A ratio of the batch's share of each contrast's variance to the residual's, above a threshold such as 2 The ratio is a worst case that ignores the size of the batch variance, its threshold has no source, and simple designs land on it exactly (two dose-1 samples sharing a lane give 2.0); the exact rule is checked against limma's nonEstimable. A batch unbalanced across the doses belongs in the design, as the documentation says
A batch that the design models as a random intercept compares the groups it confounds with the vehicle when the vehicle and each such group span two or more batches; a fixed batch is handled by estimability Excuse every confounded group under a random intercept; refuse confounded designs With the vehicle alone in one lane and the doses over two shared lanes, dream_voom's any-dose F-test put 17 to 19% of null genes below 0.05 (4 to 7% with the vehicle sharing lanes); with two or more lanes on each side the variance between lanes is estimated beside the doses
With random intercepts, the replicates of a dose group are the levels of each grouping among its samples Samples, with a unit nested one to one in every dose group refused The replicate is the unit: one animal of two samples per treated dose under `(1
A unit nested one to one in the dose groups, such as one animal per dose with two samples each under `(1 animal)`, is refused with advice to pool each unit's samples Reuse Design.check's message, which advises dropping the random effect
ETAP's minimums carry ETAP's own consequence; only unmet design and vehicle minimums make a deviation Every unmet minimum a deviation ETAP excludes a level with fewer than 2 passing samples and goes on, so a series that loses a sample at one dose follows ETAP's procedure
A step counts as half a log10 within 0.05 of 0.5, and as a full log10 within 0.05 of 1 Exact steps One decimal place of log10 is the precision of "half-log10", and both steps of a 1-3-10 series (0.48, 0.52) fall within it
n_dose_groups counts the dose groups that keep a sample, and n_dose_groups_estimable the treated groups the design can compare with the vehicle One count of the vehicle and the estimable groups The printout says how many groups keep a sample, and readers took n_dose_groups for that number; PR 10's spare groups need the second count, with the vehicle
ETAP's minimums stay in dose_designs.py, as functions on plain inputs in a section of their own A private rule-set module now The repository keeps a private module only when two modules share it; PR 14 can move them when a second module needs them
The report is an immutable class with its settings kept as JSON text A frozen dataclass The settings hold the axis's dict, which a read-only mapping would leave mutable, and run records need them as JSON
The reading of dose columns lives in one private module, cytepool/_doses.py, shared by DoseAxis, the check and the simulator of #79 A second copy of the rounding rule One implementation of the checks and messages, which tests/test_dose_axes.py pins
The section on simulated dose series (#79) moves with the dose axes into "Dose response", after ETAP's design minimums, with its limits, checks and Validation section Leave it in "Designs, linear models and contrasts" It runs the spline F-test of the dose axes on simulated series, so it belongs beside them with the other dose methods
Design.check's numeric-codes heuristic unchanged Skip covariates by name or value The check passes no axis column to it; the chapter explains the warning on decade ladders in one sentence

Trimmed from the plan, with where it goes: spare dose groups per model set (PR 10, whose fits define the models; the chapter gives the arithmetic); rules="ntp_2018" (PR 14); ETAP's study conditions, such as species, route and duration, which samples do not show (PR 16's records); ETAP's sequencing quality metrics, which are bulk TempO-Seq metrics (not applied; the cell type's filter stands in); designs with a dose measured per sample (PR 21); a provenance record on the report (PR 16). No guide holds a dose series before PR 7, so the worked example lives in the chapter, and PR 7's guide should open with the check.

DoseAxis checked its dose column, the finiteness and sign of each dose, and
the rule that refuses two doses within 1e-8 of each other, in private
helpers of its own module. A check of dose designs needs the same reading,
and a second copy would let the two drift apart.

The reading moves unchanged into cytepool/_doses.py: real_vector,
checked_doses, column_doses and distinct_doses, with their messages.
DoseAxis keeps its refusal of fewer than two distinct doses on the axis.
The docstring addresses of dose_axes.py point to the new chapter's
section on dose axes.
A dose series can fail per cell type in ways nothing in CytePool reports
before fitting: filtering can leave a dose group without a sample in a
depleted cell type, a dose processed in its own lane or plate cannot be told
apart from that batch, which breaks the control of false positives (Lun and
Marioni 2017), and 57 of 130 single-cell dose studies had no biological
replicate per dose.

check_dose_design(cube, design, dose=axis) counts the samples, cells and
counts each dose group keeps in every cell type after the filter limma_voom
applies, fits the dose-group model of each cell type by R's qr() rule, and
calls a dose group estimable when its column, placed last, lies outside the
span of the others, as limma's nonEstimable reports it. A dose group is
confounded with a batch when the batches' indicators, those of a single
sample pooled into one, absorb it beside the design's other terms. Each cell
type is inferential, descriptive (no estimable treated group keeps a second
sample, no residual df, or an unmodelled batch confounds a group) or refused,
with a reason that says what to do. With rules="etap_2024" the report lists
the design minimums of EPA's Transcriptomic Assessment Products (US EPA 2024,
Sec. 3.4.1.3, 3.4.2 and 3.4.5.2) that the design misses, with what ETAP does
when each is unmet: a dose level ETAP excludes leaves the status unchanged.

validation/dose_design.py compares the counts with scanpy 1.12.4 and pandas,
the residual df, estimable and confounded groups with R 4.4.3's qr() and
limma 3.62.1's nonEstimable on 20 designs, the statuses and ETAP's minimums
with the same rules coded in R, and runs GSE208161, one participant per
dose, where every cluster is descriptive: 41 checks, all identical.
…heck

Dose axes were explained inside "Designs, linear models and contrasts", and
nothing said what a number of dose groups supports or how to check a dose
series before fitting it.

A new chapter, "Dose response", after "Composition tests", takes the section
on dose axes and the vehicle and adds what K dose groups support (the
degrees of freedom for dose, the largest spline, curves that leave a spare
group, and what MCP-Mod and ETAP ask), how check_dose_design decides each
status, with an example that runs in the tests, and ETAP's design minimums
with what ETAP does when each is unmet. The Validation page gains a "Dose
response" group with the dose axes section and the new dose designs
section, its summary rows, totals and command; dose_axes.py ran again with
its table unchanged. "Choosing a method", the glossary (dose group,
descriptive, rule set), the bibliography (US EPA 2024, EMA 2014, Sonigra
2022), the API reference and THIRD_PARTY_NOTICES.md (GEO series GSE208161)
follow.
The module docstring named check_dose_design and DoseDesignReport without
their top-level path, and the first lines of four properties held a colon,
which the API reference reads as a type. Both now build without warnings.
The dose design check counted samples as replicates even when the design named the animal or participant as a random intercept, so one animal sampled twice at each dose looked replicated. A random intercept of the batch excused every dose it confounded, also when the vehicle sat alone in one lane, where a review simulation put 17 to 19% of null genes below p = 0.05. A batch holding a single sample, when it was the only one, absorbed that sample and marked its dose as confounded.

With random intercepts, the replicates of a dose group are now the levels of each grouping among its samples. A random intercept of the batch, found by the grouping it makes rather than by its name, compares the doses it confounds with the vehicle only when the vehicle and each such dose span two or more batches. A sample alone in its batch joins no batch. In the report, n_dose_groups counts the dose groups that keep a sample and n_dose_groups_estimable those the design can compare with the vehicle; minimums names its consequence column when_unmet; and the printout names absorbed doses and the levels ETAP excludes. The sample filter is shared with limma_voom's, relations come from one QR, and the chapter shows how to act on the report, how to check one compound of a screen, and that the batch rule finds exact confounding only.

validation/dose_design.py now checks 46 cases, five of them new, against R's qr(), limma's nonEstimable and the new rules coded again in R, and all match. The tests catch 27 deliberate bugs, among them the 12 mutants that survived the review.
The section on simulated dose series followed the dose axes in "Designs, linear models and contrasts", and the dose axes now open the "Dose response" chapter. The section, its limits, its checks and its further reading move there after ETAP's design minimums, and its Validation section and summary row join the chapter's group on the Validation page.

Every link to the section points at its new address: the docstrings of simulate_dose_series and DoseTruth, the API page, the glossary's benchmark dose, coverage and EC50, "Choosing a method", the Validation page and the chapter test. The chapter now opens with what simulated series show, and the bibliography page lists the works each chapter cites.
The comment on the field batch_modelled of the check's inputs ended mid-sentence; it now says that a random intercept groups the samples as the batch does.
The Dose response chapter now cites the agency's 2024 standard methods and its 2026 BMDS guide, whose bibliography entries named it as US EPA and as the US Environmental Protection Agency. Both entries now spell it out, as the entry of the European Medicines Agency does, and the chapter's reading list says "the agency's standard methods" so that the name is not repeated.
@parashardhapola
parashardhapola merged commit e72f526 into master Nov 20, 2026
6 checks passed
@parashardhapola
parashardhapola deleted the dose/05-dose-design-check branch November 20, 2026 06:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant